INTRODUCTION TO THE PDP-10 TIMESHARING SYSTEM

            FOR GRADUATE ASSISTANTS AT THE A-I LABORATORY


			R.  E.  Gorin
			September 15, 1971
			Revised December 17, 1971.

            Revised again March 17, 1972 by Martin Frost

               Adapted by Larry Tesler September 1972








	This is a brief introduction to the use of the Stanford A.I.
Project PDP-10.  This guide is not intended to be complete; instead,
the goal is to supply enough information so that a novice user can
accomplish useful work without an excessively long period of total
confusion.

CONSOLES

	There are various kinds of consoles for communicating with
the PDP-10.  Assistants at the Lab will have access to two kinds:
DataDiscs and III's.  Each console consists of a keyboard and a
screen connected by cable to the computer room.

	The keyboard is always connected to the PDP-10, but the
screen may or may not be connected.  If you come to a console and the
screen is blank, be sure the POWER switch is ON.  If it is on for at
least ten seconds, it is warmed up.  If the screen is still blank,
rotate the CONTRAST knob clockwise.  If too faint, rotate the
BRIGHTNESS knob clockwise.  If still blank, hit the large ESC button
near the zero key, and then the S key.  Next try the ESC button
followed by the P key.  If still blank, the system is probably down.

	Once your screen is working, it will either say "THIS CONSOLE
AVAILABLE" or have miscellaneous printing on it.  In the latter case,
somebody else is probably using the console, but if no one is around,
type ESC followed by S; if the message changes to "THIS CONSOLE
AVAILABLE" you can use it.

	When you sit down at an AVAILABLE console, hit the CALL
button in the upper right of the keyboard once or twice.  The system
will respond in one of two ways: (1) "NO CHANNELS AVAILABLE" means
that there are already thirty-odd datadisc screens connected and the
hardware can't handle any more.  Sorry, try again later.  (2) All
messages go away and a small dot and a cursor (._) appear at the
upper left of the screen.  The screen is now connected to the
computer, but if you don't do something within a minute or so, it
will be disconnected automatically, so it is time to "log in".

Here is how to log in (simplified).  Say your programmer initials are
"OLY".  Type "L 1,OLY", that is, an "L", a space, a "1", a comma, and
your initials.  Then strike the key labelled RETURN.  The computer
will respond "ARE YOU SURE?".  Type a "Y".  Some stuff will be typed
back, followed by EXIT, ↑C, and then "._".  The system is now waiting
for another command, and since you are logged in, your screen will
not be disconnected.  More details about logging in appear later in
this manual.  But first, it is necessary to be familiar with the
console.

	Whenever ._ appears on the screen, you are typing to the
MONITOR (or "supervisor" or "system" or "executive").  This is a
program that is always around and gives you access to the software
and hardware resources of the PDP-10.  When you start to type, the
cursor splits in two parts.  The left cursor underlines the first
character you typed and the right cursor underlines the next
character you are about to type.  If you make a mistake typing, it is
possible to "edit" the text between the two parts of the cursor by
keystroke commands.  These will be decribed later.  A summary of
keystroke commands is printed on a piece of paper that is taped to
the top of some keyboards.
	Commands to the monitor are terminated by a RETURN (a large
key on the right side of the keyboard).  If you are at a console now,
try the DAY command (type "D", "A", RETURN).  The monitor may do
something in response to the command, or type a question mark if it
does not understand.  When it is ready for another command, it types
._ again.  If you command it to run a program which requires input
from the console, the system will type *_ when it is waiting for
input, instead of ._ as it does when the monitor is waiting for
input.

	The SHIFT key held down with a letter causes the capital
letter to be typed; otherwise the lower case letter is typed.  SHIFT
LOCK, as on a typewriter, makes it possible to type capitals only.
The MONITOR only recognizes capital letters in its commands, so if
you type lower case letters they will magically be translated by the
computer to capitals, if you are not too unlucky.

	The TOP key held down with another key causes the character
shown near the top of that key to be typed instead of the one at the
bottom.  There is no such thing as a Top-Lock key.

	The CONTROL and/or META keys held down with a character (with
or without SHIFT or TOP) transmit to the computer a "control"
character.  Some control characters cause editing of the text between
the two parts of the cursor ("intra- line editing").  Some are used to
communicate with interactive programs such as RAID (a debugger) and
TV (a page editor).  If you hold down CONTROL, META, TOP, and the key
that says

		<
		D

the character transmitted is "control-meta-<", sometimes abbreviated
"αβ<".  That is, "α" is an abbreviation used in local manuals to mean
the CONTROL key and "β" to mean the META key.  Believe it or not, this
character actually means something to RAID.  You must hold down all
four keys at once! The proper technique is to first push down
CONTROL, TOP, and META with two or three fingers of your right hand
(notice they appear on both the right and the left of the board), and
then strike the D key with the middle finger of your left hand.
Finally, release the special keys held by your right hand.
Hunt-and-peckers like me can devise more intricate and confusing
schemes.  By the time you finish your education, your fingers will be
able to type "αβ<" followed by "αP" with both feet tied behind your
back.
	NOTE: If you hear people talking about "control-see", they
probably mean "↑C" (CALL), which used to be a control-key character
on teletypes.  The abbreviation TTY used by the system to refer to
your console is also a remnant of teletype days.

	If you type characters before the computer is ready for them,
they are kept in a buffer and displayed on your screen.  This is
called TYPE AHEAD.  Sometimes it is not possible to type ahead, and
you must wait until the computer is ready.  You will find out when
this happens by experience.
CHARACTERS OF SPECIAL IMPORTANCE

	RETURN, also known as "carriage return" or "CR", is used to
end the line you are typing.  The return key will make the computer
send back a RETURN and a LINE FEED, which will cause a new line to be
started.

	LINE FEED, also known as "LF", causes your printer to move
down one line without changing the column it is in.  LINE FEED is not
often used when talking to the computer.  Use RETURN to terminate
lines of input.

	BS (Backspace) is used to correct a single character mistake.
When a letter has been typed that is wrong, pressing the BS
(backspace) key will make the last character typed go away.
Successive uses of the BS (backspace) will erase more characters.
Deleted characters will disappear.

	CLEAR erases the entire current line, like many BackSpaces.

	ALT MODE is a special character used by certain programs.  On
the keyboard, the ALT MODE key is labeled ALT.

	CALL (often referred to as ↑C) calls the system.  Striking
this once or twice will interrupt whatever else you are doing and
leave you talking to the MONITOR (sometimes called "the system" and
other foul names).  See "THE MONITOR", below.

	TAB is the tab character.  Typing tab makes the monitor send
back enough blanks to space your printer to the next tab stop.  Tab
stops are fixed in columns 1, 9, 17, 25, ...  (every 8 columns).

	ESCAPE (sometimes called <esc>) and BREAK (<brk>) are used to
give certain brief commands to the system.  They are always followed
by an argument of the form <letter> or <number><letter>.  For example,
<esc>C clears the screen and <esc>P refreshes it.  These commands are
used when "static" make your screen hard to read.

	<esc>O	 (sometimes called ↑O) makes any program that is
printing on your console shut up.  This is used to halt listings that
are too long.  The program keeps running but the type-out stops.

	<esc>W makes the system update the "who" line at the top of
your screen.  On the III it is updated continuously; on the DataDisc
occasionally.  If the "who" line doesn't flicker at least every couple
of seconds then the system is probably hung.  <brk>W prevents the
"who" line from being updated; it will no longer flicker, but on the
DataDisc it won't go away either, unless you type <esc>C <esc>P.

	If you suddenly discover that somebody else's job is being
displayed on your screen, type <esc>S.  If it happens frequently,
complain to the hardware guys about the "video switch".
THE MONITOR

	The MONITOR is the program that supervises your job.  Most of
the commands described below are commands to the monitor.  These
commands tell the monitor to do certain things for you.  Commands that
you issue to other programs (such as the editor commands) are
processed by these other programs.  ↑C is used to interrupt a program
and to return your job to monitor mode where monitor commands may be
issued.

	When the monitor is ready to accept a command from your
console, it will type a period (.) at the left end of a new line.
Commands to the monitor (and to most programs) are terminated by a
carriage return.  Before RETURN is typed, the line may be changed by
the BS (backspace) and CLEAR characters.

	The first thing it is necessary to understand about
time-sharing systems is that at different times you will be talking
to different programs, and the rules for interpreting what you type
depend on what program you are talking to.  In order to do CS206
exercises you will have to talk to at least four different programs,
namely: the time sharing system (ie, the monitor), the SOS text
editor (used to create and edit files), LISP, and MLISP.  Later you
may find yourself talking to MLISP programs you have written
yourself.

	To ensure that you are talking to the time-sharing monitor,
type ↑C.  No matter what program you are talking to, after typing ↑C
you will be talking to the monitor.



USING THE COMPUTER: THE LOGIN COMMAND

	Each time you wish to use the computer, you must identify
yourself through the LOGIN process.  To LOGIN, first place the console
in monitor mode by typing CALL once or twice until a period (.)
appears in the left margin.  Then type the command L followed by
RETURN.  ALMOST EVERY COMMAND LINE MUST BE TERMINATED WITH A RETURN.
The computer should then type the name of the computer system and on
a second line it will type #.
	A few things can go wrong at this point.  The most likely is
the message "JOB CAPACITY EXCEEDED".  This means that so many jobs are
already running that the time-sharing system is fully loaded and you
won't be allowed to log in.  This usually happens only on weekday
afternoons.  There are generally fewer users nights and weekends, and
with a lighter load at those times, the time sharing system offers
faster response.

	When the # appears, LOGIN will wait for you to identify
yourself.  Type your project number, a comma and your programmer name.
If the name you use is associated with a disk area (explained below)
then you will be logged in without further hassle.  If the name you
use has no disk area, LOGIN will ask "ARE YOU SURE?".  If you are
sure, then type Y, otherwise type something else.

	Now, you should be nearly logged in.  If there is a general
notice for all users, then it will be typed on your console after you
have logged in.  If there is a personal message for you, LOGIN will
ask you whether you want to read it now.  After you have read your
personal message(s), LOGIN will offer to delete it (them).

	LOGIN requires a project number and a programmer name (2 or 3
letters).

	LOGIN Example: (Comments about the example appear at the
right side of the line and are preceded by semicolons.)

↑C				;CALL to get to monitor mode
↑C				;↑C until a dot appears
.L				;type L to LOGIN
JOB 1 Stanford 6.05B 3-14-72	;you're job 1
#206%AA1			;project = 206 , programmer = AA1
ARE YOU SURE? Y			;new user.  Type Y to confirm
NEW PASSWORD =			;system asks you for new password
				; (see next page about passwords)
Friday	17-MAR-72	1853	;system types the date
				;	and various messages
I.M.  Volleyball Practice 10AM Saturday, Mens' Gym.
HAPPY ST.  PATRICK'S DAY!
	
0005-DAY COMPUTER MAINTENANCE FORECAST:
 Saturday: 0000, 0100, 0200, 0300: PMP; 1800, 1900, 2000: REG;
 Monday: 0800: GJG;
 Tuesday: 0800: GJG;
EXIT
↑C				;system types ↑C and leaves you in
.				;	monitor mode
LOGGING IN THE FIRST TIME

	The first time you LOGIN, separate your project (206) and
your programmer name with a percent sign (%) instead of a comma.  The
system will then ask you to set your (new) password.  A password is 1
to 6 letters or digits, and should be followed by a RETURN.  Should
you later decide you don't like your password, you can change it by
logging in with the percent sign instead of a comma.  You must give
your old password before specifying your new one.  DON'T FORGET WHAT
YOUR PASSWORD IS! The system doesn't print it when you enter it!


AVOIDING PRINTOUT OF SYSTEM MESSAGES DURING LOGIN

	When logging in, if you separate your project and your
programmer name with a slash (/) instead of a comma, then messages
that you have already seen may not be printed.


LOGOUT (KJOB)

	When you are finished using the console, it is necessary to
LOGOUT, i.e., kill the job that was initiated by LOGIN.  The command
to do this is called KJOB, which may be abbreviated as K.  To kill
your job, it is necessary for your console to be at monitor level.
Then type K (and RETURN).  The line "KJOB" will be typed on your
console and your job will be terminated.  In some circumstances,
LOGOUT will type "File director has been deleted." This message means
only that your file directory has been found to be empty so it was
deleted.  A directory for a user is created by LOGIN when the user
types "Y" to the "ARE YOU SURE?" message.  If your directory is
deleted, then the next time you LOGIN you will have to reassure LOGIN
again.

	LOGOUT example:

↑C
↑C

.K
File directory has been deleted.

Job 1, [206,AA1] Logged off TTY22 18:59 17-Mar-72
0.01 hours, console time.
0.01 minutes, cpu time.
2.75K average core.
KJOB

	After KJOB, the sytem waits a minute or so and then
disconnects your screen from the computer.  The message "THIS CONSOLE
AVAILABLE" is displayed once more.  This also happens if you begin to
log in and don't finish in a reasonable amount of time.
FILES

	Many of the monitor commands mentioned below refer to one or
more FILES.  A file is a collection of information stored on a disk.
Thus it can be retained from one session to another.

	Filenames in this system are composed of two parts, called
the name and the extension.  The name can be up to six characters; the
extension (which is optional) is limited to three characters.  If an
extension is used, it is separated from the name by a period.  For
example, the filenames

	FOO			F1.A
	GARPLY.ZOT		BAZ12.GAR

are all valid.  Filenames can include letters and digits.  Avoid the
use of the characters

	[ ] , .  *

(square brackets, comma, period and asterisk) in filenames.  These
characters are used to mean other things to programs that know about
files.

	Each user of the system has what is called his "disk area",
which is simply the collection of all his files and which is
identified by his project number and programmer name (PPN) enclosed
in square brackets, eg, [206,ME].  You can reference a file that
belongs to someone else by typing the owner's PPN after the file
name.  For example, this write-up is in the file:

	INTRO[S,TES]

(Most programmer names are three characters instead of two as here.)



USEFUL MONITOR COMMANDS

	These commands are shown preceded by a "." indicating that
the console is at monitor level.  The "." is printed out by the
monitor.  Each of these commands must be terminated with a RETURN.

	In the descriptions below, <filenm-ppn> means any legal
filename, WITH OR WITHOUT a PPN; <filenm> means a legal filename
WITHOUT a PPN; <ppn> means just a PPN (enclosed by square brackets).
.CREA <filenm>
	This command CREAtes a file with the given name and starts
the SOS text editor in Insert mode so that you can type in the text
of the file.  See the section below on SOS.

.ED <filenm-ppn>
	This starts the SOS text editor in Command mode so that you
can EDit the named file.  (See SOS below.) If a PPN is present, the
result of your editing will be a file on your disk area; the original
file will not be changed.

.DI
	This prints your DIrectory, that is, a list of your files and
their sizes and dates of creation.  There is a limit to the amount of
space users are allowed; that limit for most people is 150K (K=1024
words).  If a user exceeds his limit, his files may be purged (ie,
disappear).

.DI/F
	This lists all your files but without their sizes or creation
dates.  Thus this command is Faster with the /F.

.DI <ppn>
	This lists all the files on the given disk area.  This command
may be followed by "/F" with the same result as the previous command.

.TY <filenm-ppn>
	This TYpes the indicated file on your console.

.DEL <filenm>
	This DELetes the indicated file from your disk area.

.W
	This prints a list of Who is using the computer and what they
are doing.  On displays, the information is updated constantly.  The
information given for each job is similar to what is displayed on
that job's screen by <esc>W.  On DataDiscs, the whole list may not fit
on one screenload; type up-arrow (↑) to move the list up, ↓ to move
it down, E to exit.

.SY
	This does the same as W, but in a different format.  The
information is not updated at all.

.TI
	This tells you how much computer (CPU) TIme you have used 1)
since you logged in and 2) since you you last gave this command.
.C
	This tells you how much Core memory you are using and the
maximum amount available.  If you type a (decimal) number after "C",
your core size will be set to that amount.  Core sizes are given in
units of K, where 1K = 1024 words.

.PJ
	This prints your Job number.

.PPPN
	This prints the PPN you logged in with.

.DA
	This prints the time of DAy, the day of the week and the
date.

.SEND <pn>
	This will allow you to SEND a message to the person whose
programmer name is <pn>.  For example, to send a message to Martin
Frost, use the command: SEND ME the SEND program will type
instructions about how to use it.

.RESO
	RESOURCES available, such as disk space in 128 word blocks,
tape drives, A-D converter.

.SPOOL <filenm-pppn>

	This causes the file to be queued for later listing on the high-
speed printer in the computer room.  Although the spooling program will
complete its work in a few seconds, it usually is several minutes before
printing actually begins.  When it is done, the system will type the message
"SPOOLING FINISHED".  While waiting, you can run other programs.
SOME EXAMPLES OF THE ABOVE MONITOR COMMANDS

(Monitor commands are preceded by a dot in column 1)

↑C
↑C

.CREA TEST

00100	THIS FILE IS USED TO DEMONSTRATE MONITOR COMMANDS
00200	THAT START UP THE SOS TEXT EDITOR.  SEE THE SECTION
00300	ON SOS.
00400	$
*E

EXIT
↑C

.ED TEST

*I400
00400	NOW WE ADD ANOTHER LINE.
00500	$
*E

EXIT
↑C

.DI

19-MAR-72 1325
FILENAME.EXT	 SIZE	 LAST WRITTEN
 [206,AA1]
QQSVED.RPG	 128	 19-MAR-72
PPSAV.DAT	 128	 19-MAR-72
TEST		 128	 19-MAR-72
	TOTAL= 384


EXIT
↑C

.DI/F

19-MAR-72 1325
 [206,AA1]
QQSVED.RPG
PPSAV.DAT
TEST

EXIT
↑C
.DI[206,ME]

19-MAR-72 1326
FILENAME.EXT	 SIZE	 LAST WRITTEN
 [206,ME]
TEST1		 128	 19-MAR-72
TEST2		 128	 19-MAR-72
INTRO		 10.1K	 19-MAR-72
DEMO		 128	 19-MAR-72
	TOTAL= 10.5K


EXIT
↑C

.TY TEST

00100	THIS FILE IS USED TO DEMONSTRATE MONITOR COMMANDS
00200	THAT START UP THE SOS TEXT EDITOR.  SEE THE SECTION
00300	ON SOS.
00400	NOW WE ADD ANOTHER LINE.





EXIT
↑C

.TY DEMO[206,ME]

00100	THIS IS JUST A SHORT FILE USED TO DEMONSTRATE
00200	ONE OF THE MONITOR COMMANDS.





EXIT
↑C

.DEL TEST

DELETED:TEST

EXIT
↑C

.
 RUNNING A PROGRAM: MORE MONITOR COMMANDS

	The commands below refer to what is known as a "core image".
Your "core image" is a picture of your program which is sufficiently
complete so that the program may be restarted from the information
provided.  The total state of a job is not reflected in the core
image; information about the present condition of input- output
devices is NOT saved by the SAVE command.  You may not CONtinue your
job after SAVE-ing it; you must restart it.

.R <filenm>
	This causes the named system program to be
read in and started under your control.  If the <filenm> is followed
by a (decimal) number, the program will be run in that amount of
core.

.SAVE <filenm>
	This causes your current core image to be saved on your disk
area in a file with the given name.  If the filenm has no extension,
the standard dump extension ".DMP" will be used.  THE SAVE COMMAND
SHOULD BE USED VERY SPARINGLY (IF AT ALL) BECAUSE DUMP FILES TAKE UP
A LOT OF ROOM (on the disk).

.RUN <filenm-ppn>
	This causes the program SAVEd in the named file to be read in
and started under your control.  If the filenm has no extension, the
extension ".DMP" is assumed.  If the <filenm-ppn> is followed by a
number, the program will be run in that amount of core.

.GET <filenm-ppn>
	This loads the file named (which must have been created by
the SAVE command) into your core image, but does not start it.  If the
filenm has no extension, ".DMP" is assumed.

.S
	This Starts whatever program is in your core image.

.CON
	This causes your program to CONtinue from the point where it
was interrupted, if such a continuation is possible.


 SOME EXAMPLES OF THE ABOVE COMMANDS
 (Without the computer's responses)

.R LISP 20
.SAVE PROG
.RUN PROG
.GET PROG
USING THE SYSTEM LINE EDITOR

	Characters you type on your keyboard do not go directly to the
monitor or to the program that is waiting for input.  They are
intercepted by a special program called the SYSTEM LINE EDITOR.  This
program buffers characters, that is, it saves up a "line" at a time
before transmitting the characters to the program waiting for input.
The buffer can hold up to about 150 characters at a time.

	For example, if you type "CREATE FOO", the system line editor
saves up the characters and does not send them on to the monitor.
They are only sent on when you type an ACTIVATION CHARACTER.  Examples
of activation characters are RETURN, ALT-MODE, and LINE-FEED.  Also,
any <ctrl> or <meta> character that does not mean anything special to
the system line editor is considered an activation character; for
example, <ctrl>J will put a "J" in the buffer and then activate the
program that is waiting for input, while plain "J" puts "J" in the
buffer but does not activate the program.  Note that the RETURN key
puts BOTH a CR (RETURN) and a LF (LINE-FEED) in the buffer and then
activates the program.  Finally, a program can specify that certain
seemingly normal characters (or even all characters) can activate it;
thus, the debugging program RAID is activated by such characters as
">" and ";".

	On a display console, you can tell what characters are in the
buffer because the left cursor underlines the first character in the
buffer.  The right cursor underlines the position at which the next
character you type will be put into the buffer.  Normally, this is at
the end of the line.  However, if you want to make corrections to a
line before activating the program, you can make the right cursor move
back and forth along the screen (but never further left than the left
cursor) and thus edit the line that is in the buffer.

	The system line editor considers certain characters to be EDIT
CONTROL CHARACTERS.  You already know about BS (BACKSPACE), which
chops the last character off the line, and CLEAR, which empties the
buffer completely.  The other edit control characters all use EITHER
the CONTROL key OR the META key.  The edit control characters that use
the CONTROL key are as follows:

	<ctrl><BS>	Move the cursor left one character WITHOUT
            erasure.

	<ctrl><SPACE>	Move the cursor right one character WITHOUT
            erasure.

	<ctrl>TAB	Move the cursor to the right end of the line.

	<CTRL>S<char>	Skip: Move the cursor right to the next
            occurrence of the character <char> IF it occurs.
	<ctrl>K<char>	Kill: Erase all characters from the one above
            the right cursor up to, but not including, the next
            occurrence of the character <char> IF it occurs.

	<ctrl>D		Delete: Erase the single character above the
            right cursor.

	<ctrl>I		Insert: Enter INSERT-CHARACTERS mode.  Each
            character typed in this mode is INSERTED into the buffer
            just to the LEFT of the right cursor.  All the characters
            from the right cursor to the end of the line are shifted
            RIGHT one to make room for it.  INSERT-CHARACTERS mode is
            automatically cancelled when the next EDIT CONTROL or
            ACTIVATION character is typed.

	<ctrl><digits>	Repeat factor.  Hold down the CONTROL key
            while typing all the digits.  The number thus entered is
            used as a repeat factor by the commands <ctrl><space>,
            <ctrl><BS>, and <ctrl>D.  Thus, <ctrl>6<ctrl>D will
            delete 6 characters while <ctrl>9<ctrl>9<BS> will move the
            cursor left 99 characters, i.e., to the left end of the
            line.  <ctrl><digits> is sometimes abbreviated α# in
	    documentation.

	The META key held down with a character will insert that
single character into the buffer to the left of the right cursor.
Thus, <meta>B is identical to <ctrl>IB, except that the latter leaves
the editor in INSERT-CHARACTERS mode while the former does not.

	If the right cursor is in the midst of the line, typing a
character with no control keys merely puts it into the buffer above
the cursor, replacing the character that was previously there, and
then moves the cursor right by one character.

	The system line editor treats TABs in a strange way that is
sometimes mystifying to the user.  A TAB is represented in text files
by a single character, but displayed on the screen as a series of one
to eight spaces, enough to bring the printer to a column numbered
8⊗i+1, e.g., column 1, 9, 17, etc.  The system line editor solves this
contradiction by temporarily representing a TAB that expands to N
spaces by the sequence TAB, N spaces, TAB.  You can not see this on
your screen, but it explains why some edit commands seem to treat a
gap in the line as a single character (TAB) and sometimes as several
characters (spaces).  For example, <ctrl><space> will move the cursor
right over a TAB and thus may move several character positions on the
screen, while plain <space> or any plain character will replace the
first space of the gap by the given character and move the cursor
right only one position.  As a side effect, the latter operation will
destroy the integrity of the TAB, leaving only spaces up to the next
column 8⊗i+1.  Furthermore, <ctrl>S<TAB> will skip to any TAB that has
not lost its integrity but <ctrl>S<space> will only skip to honest
spaces and not to TABs that appear on the screen to be spaces.
	 To confuse things further, after you have typed an activation
character, you can continue to type ahead even though the program may
not have actually processed all the characters already transmitted.
Characters that have been transmitted but not yet processed are kept
in another buffer called the TELETYPE BUFFER.  You can not edit
characters in the teletype buffer, so once you have typed the
activation after a line, that line is unchangeable.  Suppose however
that what you have typed will do something drastic and unthinkable,
such as destroy your core image, or clobber a file, or delete half
your program, or expose a scandal in the government.  Suppose
furthermore that the program has not yet processed the command, i.e.,
that it is out of the SYSTEM LINE EDITOR BUFFER but not yet out of the
TELETYPE BUFFER.  You may believe this to be the case because no "*"
has been typed back by the program or because the WHO line at the top
of your screen shows that the program is still running (RUNQ) or
waiting for the disk (DIOW) rather than waiting for input (IOWQ) or
stopped (STOP).  Or you may just have a hunch, or you may be so
panicked that any odds are worth it.  In that split second when your
adrenalin charges out of your abdomen and begins its creeping march
through your blood vessels, it will be well to remember the following
advice: HIT THE CALL BUTTON.  This action always CLEARS THE TELETYPE
BUFFER.  What characters have already been processed by the program
are gone to their dirty deeds, but the rest are rescued.  After
recovering your composure, you may wish to type the CON (CONTINUE)
command to let the program continue, and type some different input.
Or you may wish to forget it and run another program.  Or cry.
USING SOS, THE TEXT EDITOR

	Disk files provide intermediate and long term storage for
programs in our system.  The text editor named SOS provides a
convenient method for creating files, and modifying existing files.
The following is a brief introduction to SOS.

	SOS has four modes of operation:

	1.	Insert Mode
	2.	Command Mode
	3.	Alter Mode.
	4.	Intra-line edit mode.

Characters that are typed have different effects in each of the
modes.  To start SOS, use one of the monitor commands

		CREA <filenm>
		ED <filenm-ppn>

CREA will cause a new file to be
created and will start SOS in Insert mode.  ED will grab the indicated
file and start SOS in Command mode.


INSERT MODE

	Insert Mode is used to put text into the file.  In Insert
mode, SOS will type a line number and wait for you to type a line.
While typing the line, BS (backspace) and CLEAR can be used to "take
back" the line before SOS sees it.  Terminate the line with a RETURN.
SOS will then type another line number.  (If you type ahead of the
response to the RETURN, no harm will be done.)

	To go from Insert Mode to Command Mode, type ALT MODE.  This
will erase the current line, so be sure that you are at an empty line
when you type ALT MODE.


COMMAND MODE

	Command mode in SOS is signified by an asterisk (*) at the
left margin.  In this mode, the characters that you type are
interpreted as commands to SOS.  There are many commands; some of the
more useful ones are described below.
ALTER MODE

	Alter mode is a remnant of teletype days.  Use Intra-Line Edit
Mode on displays.

	In alter mode, SOS allows you to get inside a line and change
parts of it, without retyping the entire line.  In alter mode, the
characters that you type are interpreted as commands that direct
particular changes inside the line.

INTRA-LINE EDIT MODE

	Again, you can get inside a line and change it without
retyping all of it.  The system line editor does the editing; thus,
the control characters you use are the familiar ones taped to the top
of some keyboards.  In contrast, ALTER mode has an entirely different
and confusing set of editing characters, so don't use ALTER mode --
use INTRA-LINE EDIT mode.


EXAMPLE OF USING SOS

	When you say CREATE followed by a file name, SOS will start
and type a line number to prompt you:

.CREATE FILE

00100	SOS TYPES A LINE NUMBER TO PROMPT YOU.
00200	AFTER FINISHING EACH LINE, TYPE "RETURN" TO
00300	GET TO THE NEXT LINE.  WHEN YOU GET TIRED OF
00400	TYPING IN LINES, TYPE "ALT MODE".  "ALT MODE"
00500	WILL BE TYPED BACK AS A "BASEBALL DIAMOND" AND
00600	IT WILL ERASE THE CURRENT LINE.
00700	THE DOLLAR SIGN ON THE LINE BELOW REPRESENTS "ALT MODE".
00800	$
*

	When SOS prompts you by typing a line number, you are in
Insert mode.  Typing a line will put the line into the file.  Typing
ALT MODE will bring you to SOS Command Mode.
SOS COMMANDS

	When the asterisk is showing in the left margin, you are in
(SOS) Command Mode, in which the following commands are legal:

	I	Insert text.  (Puts you into INSERT mode.)
	P	Print Text.
	<lf>	Print next line.
	<alt>	Print previous line.
	E	Exit from editor.  (Replace the old file with
				the edited file.)
	W	Save my present modifications on the disk.
				(Replaces old file.)
	G	Go: Exit and Execute.
	D	Delete text.
	N	Renumber my file.
	F	Search for a given text string.
	S	Make string Substitutions.
	A	Alter a line.  (Puts you into ALTER mode.)
	Z	Better than A.  Puts you into INTRA-LINE EDIT mode.

	In SOS, commands are usually modified by suffixing a range
specification.  The range specification tells SOS what area of the
file to modify by the command.  The usual way to specify a range is by
naming two line numbers separated by a colon.

	For example, 300:450 is a valid range specifier.  In the text
above, it would include lines 300 and 400, and no others.

	A period (.) may be used instead of a line number to specify
the "current line".  The "current line" is essentially the last line
that was referenced (successfully).  An asterisk (*) means the last
line on a page (for the purpose of this explanation you have only one
page).  Simple arithmetic can be used in specifying range boundaries.
200+3 means the third line following line 200 (generally this is not
the same as line 203).  The range 200!3 means start at line 200 and
use three lines in the range.  (In the file above this means lines
200, 300 and 400.)


	I	Insert text.

	This command puts you into Insert mode.  It takes as its first
argument the line number at (or immediately after) which to insert
new text.  For example, in the file above, I800 will allow me to
insert at line 800 and onwards.  The second argument is optional.  If
present it must be preceded by a comma and it will specify the
sequencing increment that is added to each prompting line number.
	I220,20 will allow me to insert lines 220,240,260,280.
	To get out of insert mode, back to editor command mode, type
ALT MODE.  (Remember: When in Insert mode, type ALT MODE only on a
blank line or on a line that you want to throw away.)

	P	Print lines.

	The P command takes as its argument a range.  The lines in the
range will be typed.  If no range is given, the range used is ".!16";
ie, 16 lines are printed starting with the current line.

	<lf>	Print next line.

	When in command mode, if you type just a LINE FEED, SOS will
print out the next line, that is, the line just after the current
one.

	<alt>	Print previous line.

	When in command mode, if you type just an ALT MODE, SOS will
print out the previous line, that is, the line just before the
current one.

	E	Exit from the editor.

	This is (nearly) the only way to get out of SOS and actually
leave the proper file on the disk.  SOS operates by keeping large
portions of your file in core while editing.  No actual changes to the
file that's being edited are made until the E (or W) command is used.
Then, the data from core is written on the disk in a form that can be
used again by the editor or by other programs.

*****	WARNING: ALWAYS LEAVE SOS BY THE E COMMAND IF YOU WANT YOUR
FILE UPDATED.  Conversely, if you make a tremendous mistake while
editing, you can protect your original file from modification by the
editor by typing ↑C (provided you didn't use the W command) to get
back to the Monitor.
*****	WARNING: THE COMMANDS E, W AND G ALL TAKE AN OPTIONAL
ARGUMENT.  THIS ARGUMENT IS A FILE NAME AND THE EDITED FILE WILL BE
NAMED WITH THIS NAME.  For example, if you type the command EXIT then
the updated file will be named "XIT."

	W 	Save my Edit on the Disk.

	The W command causes all the changes that you've made thus
far to be written on the disk (replacing any previous copy of the
same file).  After the W command finishes, you can continue editing
from the same place in the file as before the W command.  Nothing is
changed.  It is wise to type W from time to time in order to save all
the updating you have done in case the system crashes.

	G	Go: Exit and Execute.

	The G command is just like the E command, except that after
leaving SOS, control is transfered to a magical program named RPG
which will try to remember the last thing you did before editing.
This explanation will be made clearer later in the quarter.

	D	Delete lines.

	The D command takes a range specifier to name the lines to
delete.  For example, D100 will delete line 100.  D1000:1250 will
delete all the lines between 1000 and 1250, inclusive.

	N	Renumber the file.

	The command N with no arguments renumbers all the lines in
the file, starting at line 100 with an increment of 100.  There are
more refinements, for which see [Savitzky].

	F	Find Matching Text.

	The F command takes a string and a range as its arguments.
The string to search for immediately follows the F and it is
terminated by an alt mode.  The range, if any, follows the alt mode.
	If there is no range given, the search begins on the next
line (essentially ".+1") and continues to the end of the file.  If a
range is given, the search will take place entirely within that
range.
	FSEARCH STRING$/1 will search for the string "SEARCH STRING".
The dollar sign ($) represents an alt mode.  The range /1 means "all
of page 1." When the first occurrence of "SEARCH STRING" is found,
the line where it occurs will be typed.  Note that if "SEARCH STRING"
is broken over two lines then it will not be found.
	FLINE$100:500 will search lines 100 to 500 for the string
"LINE".  In the file above, it would match lines 100, 200, 300 and
400.  The command would locate line 100 and type it.  If you want to
find more occurrences of "LINE",use the command F (Remember to follow
the F with a RETURN).  This would find line 200.
	S	Substitute Command

	Occasionally it becomes necessary to change one text string
into another.  The S command is used to do this:
	Sold string$new string$range will find each occurrence of
"old string" in the range given and replace it by "new string".  The
dollar signs ($) represent the ALT MODE character.
	SCAR$CDR$/1 will change "CAR" to "CDR" everywhere (on page
1).  This sort of substitution must be done CAREFULLY, lest it be done
"CDREFULLY".	

	Z	Zip into INTRA-LINE EDIT mode.

	The Z command, followed by a range will allow you to change
the contents of each line in the given range.  When a line is being
altered, the line is displayed on the screen with the familiar
cursors.  AFTER THE CURSORS APPEAR ON THE SCREEN, you can edit it
using the same CONTROL and META commands you use to edit commmands.
Typing RETURN finishes the edit of the line.  Typing ALT instead
aborts the edit, leaves that line unchanged, and returns to COMMAND
MODE immediately.  Typing META and RETURN breaks the line into two
parts at the right cursor; editing of the left portion is terminated,
and the right portion is assigned a new line number a little larger
and you can edit it.

	Other commands.

	The SOS manual by Savitzky explains the other editor
commands.  Also the commands mentioned above are explained in greater
detail.
 SECOND SEGMENT

	The virtual addressing space on the PDP-10 ranges from
0-777777 octal.  On our system, any one job can only address a limited
portion of that space.  The portion allotted to a job is divided into
two SEGMENTS.  The first segment includes locations 0-C where C is the
"CORE SIZE" indicated on the WHO line and used by the C (CORE) command
of the monitor.  The second segment includes locations 400000-S, where
S is normally not under user control, but can be discovered by use of
the C command.  Locations C+1 to 377777 are illegal as are locations
S+1 to 777777 -- if the program tries to access them the message ILL
MEM REF is given.  Note that locations 0-17 octal are the working
registers (accumulators, indexes, and stack pointers), and that other
low-numbered locations are interrupt cells and cells describing
properties of the job of interest to the system.

	Although the user thinks of his entire addressing space as if
it were stored in a random access memory at locations numbered
0-777777, in the time-shared PDP-10 the addressing space is actually
stored in physical core memory at quite different locations.
Locations 0 to 15 correspond with the high-speed registers while the
program is active, but are stored into the beginning of the first
segment while other jobs are active.  The first segment is stored in a
consecutive block of core locations whose base address is kept in a
relocation register while the job is active.  The second segment is
stored in a different consecutive block and uses a different
relocation register.  None of this is the concern of the user, since
the hardware and time-sharing system automatically manage these
registers.  The user has the illusion of his own memory that is
addressed from 0-777777.

	The interesting thing about a second segment is that several
jobs can share the same second segment.  Usually, the second segment
is read-only, and any attempt to change a location in it will result
in an ILL MEM REF and abortion of the attempt.  Thus, a reentrant
program can be shared by several jobs safely by keeping it in a shared
second segment.  When you run SOS, for example, your WHO line will
show the SEGNAM "SOS".  This means that the editor only appears in core
storage once even though many people may be editing simultaneously.
Their text is kept in their private independent first segments.
Similarly, when you are using the SAIL compiler or running a SAIL
object program, the SEGNAM is SAISG4, which means that all other jobs
using SAIL are accessing the same copy of the intrinsic functions and
memory management routines as yours.

	When you do a SAVE, only the first segment of your core image
is copied on your disk, and a note is made of the name of your second
segment (e.g., SOS or SAISG4).  Then, when you GET or RUN that disk
file, your job is automatically connected back to the second sgement
of that name (re-read from a special disk area if there are no copies
around).  There is a special command SSAVE which saves both segments.
It is usually used only when creating new system programs.  See Moorer's
Monitor Manual (Chapter 2) for more information about such matters.
 DECIMAL AND OCTAL

	The FAIL assembler and RAID debugger expect you to use OCTAL
radix most of the time, while the SAIL compiler expects DECIMAL.  MLISP
expects decimal, while LISP expects octal.  The monitor usually talks
in octal.  Most compilers and assemblers have a way to change radixes
for input and/or output or to mark certain numbers as being in the
abnormal radix.  Be cautious about this.  A general rule is that
storage addresses and memory dumps are usually in OCTAL while line
numbers, repeat factors, and algebraic constants are in decimal.

 COMPILERS

	SAIL is an extension of ALGOL-60 which is currently
undergoing significant revisions to incorporate multi-process
backtrack control structure without sacrificing respectable execution
efficiency.  It is probably the most popular language of programmers
at the Lab.  The Sail compiler inputs a text file produced by SOS or
another editor (TECO, TV, etc.), and outputs a "REL" (relocatable)
file of machine instructions.  If the text file was named FOO.SAI, the
relocatable file will be named FOO.REL.  One or more relocatable files
can be loaded by the program LOADER to produce a core image.  See the
Monitor Manual Chapter 1.

	FAIL is the second-best assembler for the PDP-10.  If the assembly
language text is on file BAZ.FAI then the FAIL assembler will produce
a relocatable file BAZ.REL.  FAIL and SAIL programs can be loaded
together and call each other.

	FORTRAN is also available but I don't know anything about it
and don't want to.

	LISP is the most important A.I. language because of its
symbolic expression capabilities, but it is not the most widely used
because of its unfamiliar notation and inefficient arithmetic.  CS206
and most other LISP users here write programs in MLISP, which is
translated by a preprocessor to LISP.  The advantage of MLISP is that
the notation is Algol-like and thus more familiar and more compact.
LISP programs can be interpreted and run interactively; that is, you
can make LISP do things, tell you the values of variables, and debug
without recompiling as you must with SAIL.  There is also a LISP
compiler which produces good object code except for arithmetic.

	Currently under development is LISP70, which has a
multi-process backtrack control structure, pattern-matching, and an
extensible Algol-like notation.  It also permits type declarations,
thus allowing efficient arithmetic.  Its capabilities will thus be
quite similar to SAIL but its style and advantages will be different.
	Also available at the Lab is MICRO-PLANNER, developed at MIT.
It features limited pattern-matching and backtracking capabilities and
runs very slowly.  The present popularity of backtracking is due
to the success of this minimal trial implementation, many years ago.


	One final "compiler" is PUB, the document compiler.  It takes
a rough-layout manuscript and produces a fine-looking document that
can be printed on the terminal, line printer, and soon on the Xerox
Graphic Printer (XGP or LDX).  It is as much work to learn and use as
any compiler, and it is fairly slow running, but it does produce
fine-looking documents.  You will probably use it to publish your
thesis, many years from now.
THE SAIL LANGUAGE -- DIFFERENCES FROM ALGOL-60


                             IDENTIFIERS

Capital and small letters are not distinguished.  These are all the
same to SAIL:

	alpha
	Alpha
	ALPHA

Although the length of an identifier is unlimited, it is recommended
that it be distinguishable by its first six characters.  [Only the
first six characters are available in the run-time symbol table used
by RAID (DDT).  Problems also arise when a large program is broken up
into separately compiled modules, and when an assembly language
program is loaded with a SAIL program.]


                             PROCEDURES

Types of formal parameters are specified within the parentheses of
the procedure declaration, along with the names of the parameters.

	PROCEDURE P(INTEGER A, B; STRING S) ;

Numbers and strings are passed by value and arrays by location.  To
pass a simple variable by location, use the qualifier REFERENCE in
the procedure declaration.

	PROCEDURE Q(REFERENCE INTEGER I; INTEGER ARRAY P) ;
		P[I] ← I ← 4*I + 1 ;

There is no Algol-call-by-name; i.e., if an expression is an actual
parameter, it is evaluated only once, at the time of the call.

A recursive procedure must be declared as such.  A typed procedure
must have a RETURN statement somewhere in its body.

	RECURSIVE INTEGER PROCEDURE FACTORIAL(INTEGER N) ;
		RETURN(IF N=0 THEN 1 ELSE N * FACTORIAL(N-1)) ;


                        ARITHMETIC OPERATORS

Multiplication *

Division / %	The latter is integer division INT%INT→INT

Modulus MOD	Uses infix notation: A MOD B

                              CONSTANTS

Real	6.4@-7 = .00000064

Integer	-14

String	"This is how to get a "" into a string"

Octal Integer '7677


                          STRING OPERATORS

Automatic conversion of small octal character code to string value

	CR ← '15 ; LF ← '12 ;

Concatenation

	B ← "Long " & "message." & CR ;

Function CVS to convert integer to string for output

	STR ← CVS(14-J)

Function OUTSTR to output a string to the terminal

	OUTSTR("This is a " & B & LF & " X = " & CVS(X) & CR & LF) ;

Equality of strings

	IF EQU(STR, "D<<@.") THEN ...

Length of a string

	L ← LENGTH(STR)

Substring

	STR[4 TO 7]
	B[∞-6 TO ∞]	...∞ means last character

                              ITERATION

	FOR I ← A+B STEP C-1 UNTIL Q*R DO ...

In the above, A+B and C-1 are evaluated just once each, but Q*R is
evaluated each time through the loop.  But if the STEP expression is
a simple variable, it is re-evaluated every time too.

	WHILE A<0 OR B>0 DO ...

	DO ...  UNTIL (BOOL ∨ ¬LOOB) ∧ Q>Y≥0
           OTHER FEATURES OF SAIL (SEE MANUAL FOR DETAILS)


	The `*' marks facilities recently added to SAIL and not yet
	in the manual.  See SAIL.NEW[UP,DOC]

 CASE Statements and Expressions

*SIMPLE PROCEDURES	Extra efficiency, a few restrictions

 SCAN, INPUT		String scanning, file input

 LEAP			Powerful associative processor, set and list
			operations

*Multiple processes

*Macros and Conditional Assembly
WHAT TO DO WHEN THE SYSTEM CRASHES

	Despite years of hardware-software development, our PDP-10
time sharing system is not totally reliable; some people would even
phrase it more strongly.  The system has many modes of failure.

	When the system crashes, characters will no longer echo on
the console.  That is, when a character is typed, nothing will be
printed on your console.  When the system crashes, there is
essentially nothing you can do from a remote location.  Sometimes the
system is rescued by one of the local wizards; more often, the
wizards can't be found so the system is reloaded.

	When the system is reloaded, it will type a message on every
console.  A reload causes you to lose your job; you'll have to LOGIN
again.  Reloads also destroy all information about your job, except
whatever you've saved on the disk.  (See the section about SOS).

	The system may be restarted instead of reloaded.  In this
case, you lose any IO (input - output) activity that was going on;
your core image is unchanged.  (See the SAVE command below for a
definition of "core image").

	Generally, there is nothing that can be done when the system
crashes.  Just wait patiently for it to come back; usually this is
accomplished within five minutes.

	Another way to lose is by "SWAP READ ERROR".  This is a
hardware condition, and there's nothing you can do about it.  Swap
Read Error will probably destroy your core image.  You can attempt to
continue, but that probably won't work.

	The message "PARITY ERROR" means that a core parity bit did
not agree with the parity of the word stored at the location in
question.  This could either mean that the word was in error or that
the parity bit was in error.  The CON (continue) command will attempt
to continue; if you're lucky, all goes well.  You're usually unlucky.
The parity error could be in an output buffer and your files get all
botched up.  A series of parity errors means that the core memories
are sick and the computer will probably be down in a few minutes, so
go play ping pong.  NOTE: Undetected parity errors are not uncommon.
Most mistakes are yours, but some are the fault of the software and
some are hardware, so if something strange happens see if it is
repeatable.


SYSTEM MAINTENANCE

	Routine maintenance is performed on the system on a somewhat
regular basis.  Also the system is subject to the desires of the
system programmers who may suspend normal operations up to 20 hours a
week.  When you login, a "5-Day Computer Maintenance Forecast" is
printed showing the times (in one-hour blocks) when the system will
be unavailable.
	References

	More detailed (and possibly more truthful,) information about
this system can be found in the following sources.

1.	Moorer, A-I Project Monitor Manual, Chapter I
	SAILON number 54.2

	This describes the console commands used to talk
	with the system

2.	Savitzky.  Son Of Stopgap
	Sailon number 50.2
	
	This is a description of SOS the text editor.

3.	Moorer, A-I Project Monitor Manual, Chapter II
	SAILON 55.2

	This describes the UUOs which are used by programs
	to communicate with the system.

4.	Helliwell, COPY
	SAILON 61

	This describes COPY, a general program to move information
	from one file to another.

5.	Digital Equipment Corporation, PDP-10 System Reference
	Manual.

	This describes the PDP-10 in detail.